raFS is a filing system which allows for files with long filenames and for any number of objects in directories. It stores the files you save to it on a "host filing system", e.g. ADFS, as individual files.

raFS is Freeware, written by Richard Atterer.

Part I - User Manual

• Release note - please read it!
• Introduction
• Usage - raFS' system of storing data
  • Working with discs - write-protecting, renaming, dismounting
  • Creating new discs
  • The Choices window
• Verifying corrupted discs
• Contacting the author
• Version history
• Legal notice

Part II - Technical Details

• Corrupted discs and how they are dealt with
• Behaviour in special situations
• Limits of raFS
• Known problems
• Command line interface: Desktop_raFSFiler, raFSFiler_Menu, raFS, raFS_Create, raFS_Flush, raFS_Discs, Mount, Dismount, Verify, NameDisc, raFS_Unsafe, raFS_Safe, raFS_Opt, raFS_ExecAfter
• Calling raFS from assembler: raFS_Info, raFS_NrOfDiscs, raFS_EnumerateDiscs, raFS_FindDisc, raFS_DiscInfo, raFS_MemCopy, raFS_ReadVar, raFS_SetVar
• File formats

Release note for version 1.15 (14-11-1998)

raFS is now very stable. Nevertheless, this does not mean you shouldn't be careful when entrusting your valuable data to this program. I encourage you to back up important data that you write to raFS.

The verify functionality, which is new in V1.14, is still considered beta. Please tell me about any bugs!

Important things to remember when using raFS:

• Always shut down the computer, don't just reset it.
• Always remount a disc after the path of the storage directory has changed, by double-clicking on the directory.
• Always verify a disc if accessing a file fails and raFS tells you to verify. Never try to delete a file which raFS claims is corrupt!
• Never change any of the files inside a storage directory.
• Never burn a mounted disc (with a Lock file in its storage directory) onto CD ROM! ;-)

If raFS doesn't behave as it should and the behaviour is not described in the Known problems section, please please contact me with a bug report. Describe the circumstances under which raFS failed as closely as possible. Has this occurred repeatedly in the same situation? What machine, OS version and host filing system do you use?

In case raFS overwrites the only copy of your Favourite File, don't say I didn't warn you...

Introduction

• ArcFS and SparkFS allow long filenames as a by-product of their main functionality, compaction of the files. They are reliable, but are relatively slow, and they are not for free.
• StrongHelp was written so that many single help files could be effectively stored in one large file. Actually it is not intended for containing other things, but this is possible. However, it occasionally corrupts image files.
• Just like StrongHelp, X-Files stores the files uncompacted. It is slow, contains a few bugs and spends large amounts of time compacting its image files once they grow to a size of several Megabytes.
• LongFiles is not an image filing system, instead it intercepts the calls that programs make to RiscOS for file operations. As of version 2, it is quite stable, but nevertheless, it remains a hack. The maximum number of objects in each directory is 76.
• WIN95FS is a bit expensive if you just need long filenames, but not support for WINDOW~1.
• TBAFS, which is also commercial, offers compaction and PC support.

raFS is neither an image filing system nor a hack: It has been written as "normal" filing system. The files that you save to raFS aren't stored in one large file, but as individual files in a directory structure that the program sets up on another filing system. This means that you can take full advantage of the "host" filing system's abilities to manage files, which is much more effective. Additionally, there are much better chances of retrieving your data in case something goes wrong.

raFS has the following features:

• 100% written in assembler
• Because it is not an image filing system, there are no problems when used together with InfoZip, sFTP etc., and the size is not limited to 4GB (or even 2GB if on a FileCore-based filing system).
• Buffers directory data so that accesses are very fast.
• Supports multiple "discs" (up to 50).
• Easy creation and mounting of discs with the desktop part (raFSFiler).
• Will either use the sprite area, the RMA (RiscOS before V3.5) or a dynamic area (RiscOS 3.5 and above) for its buffering. If the sprite area is used, this is done in a way that is compatible with other programs using it, e.g. Memphis.
• Will work with CDFS and Access+.
• Foreign language support.
• You are allowed to distribute this program together with commercial programs that depend on long filenames if you send me one copy of the final product and of any upgrades as long as the product is distributed with raFS. (See the legalese below.)
• Full support for files being opened multiple times (including loading/saving).
• It gives correct error numbers!

This documentation has been split up into two parts. The first part is aimed at people who want to use raFS on the desktop, whereas the second part describes the filing system's interfaces in greater detail. It is not necessary to read it as most of the information is only relevant for advanced users and programmers.

I hope you find this a useful program!

Back to the top of the page

Usage

Before you start, the way raFS manages its discs should be clear to you. Actually, the word "disc" may be misleading - raFS does not introduce a new disc format of its own. I will talk of "discs" nevertheless because they are handled in the same way as e.g. ADFS handles floppy discs: They can be created, renamed, mounted and dismounted, and their name will appear in directory displays in the form "raFS::DiscName.$. ..." Unlike with image filing systems, raFS' discs are not stored in one large file, but as single files inside a directory.

raFS can store the data saved to discs in two types of directory: One is an application directory whose name begins with "!" and which is displayed with a special icon. The second is a normal directory, which cannot be distinguished from other directories until you double-click on it. If you do this and raFS is loaded, raFS mounts (i.e. makes known to the system) the disc contained within that directory and opens the root directory of the raFS disc instead of the directory you clicked on.

If the program is not loaded when you double-click on a normal directory containing a raFS disc, or if it is loaded but you hold down the Shift key while clicking, you will see the actual directory contents: A file called !Atterer (yes, I know I'm humble to call it like that), one called !Mount and a directory A0 with further subdirectories and similarly named files.

Don't change or delete any of these files unless you know what you are doing!

It should be noted that raFS distinguishes its own directories from other ones by looking for the !Mount file and just executing it with Obey when the directory is about to be opened. The default file also installs raFS on the icon bar if it isn't already loaded, so just double-click on !Mount if you wanted to open an raFS directory, but raFS wasn't loaded. (The reason why Obey and not just Run is used is that the file's filetype may not be correct - for instance, if you burn an raFS disc onto CD ROM using a PC.)

When you mount a disc, a file named Lock is created inside the storage directory, and it is removed again when the disc is dismounted. This is used to test whether the storage directory can be written to, and the file contents help to recognize the disc when you rename the storage directory. If a disc has not been mounted before, but a Lock file is already present, raFS either refuses to mount the disc (e.g. if it is shared over a network and has been mounted on a different machine) or gives a warning, telling you to verify it, but nevertheless mounting it (because your computer crashed or was reset since the disc was first mounted).

Back to the top of the page

Working with discs

The icon bar menu offers many commonly needed operations on mounted discs. If no discs are mounted at all, the entries below the dotted line are greyed out. Read-only lets you write-protect discs so that any subsequent attempts to alter the data on them will be faulted. If a disc is write-protected, its name is ticked in the submenu. This option does not work for discs stored on DOSFS due to incorrect behaviour of that filing system. With Name disc, you can change the name of a disc. (You guessed it!) Dismount removes the selected disc from the list of discs known to RiscOS - any subsequent accesses to the disc will fail with Disc not present. You can also dismount all discs by selecting the "Dismount" menu entry without moving to the submenu. Selecting a disc name in the Verify submenu starts a verify operation for that disc - see below for details. Open root opens the root directory for the selected disc, or for all mounted discs if the entry in the main icon bar menu is selected. Important: Should you ever want to move a storage directory or rename the (hard)disc it resides on, re-mount the disc afterwards (e.g. by double-clicking on it) so that raFS knows about the new name.

The Flush menu entry is not normally needed. When you select it, all changed but as yet unsaved directories are saved within the discs' storage directories. You should manually flush raFS' buffers if the program was unable to save changes automatically due to an error. (For example, you should flush if you clicked on Cancel when you were asked to insert a floppy disc with an raFS disc stored on it.)

Back to the top of the page

Creating new discs

New discs can easily be created from the window that is opened when the pointer is moved right over the New disc menu entry. You can choose whether to use an application or a normal directory with the "App" option (or by preceding the storage directory's leafname with "!"). Having also entered a name for the new disc, drag the icon to a directory viewer to create the disc.

raFS has the useful ability to let you use a whole hard or floppy disc for one of its own discs. When you click e.g. on the floppy drive icon to display the root directory, the program looks for the !Mount file just like it does for double-clicks on directory symbols. To create a disc like this, enter the name of the hard or floppy disc's root directory (e.g. ADFS::HD.$) in the first writable, choose a name for the new disc and finally click on Create.

Back to the top of the page

The Choices window

Storage dirs mounted on startup: In the writable fields of this section you can enter the names of up to three discs by dragging the storage directories to the fields. raFS will then mount these discs automatically every time it is run.

Commands for clicks on icon bar: The commands executed when the icon bar icon is clicked on can be changed here independently for Select/Adjust and any combination of the Shift/Ctrl keys. See here for details on the commands used by the default settings. By default, clicks cause the following actions:

• Select opens the root directory of one of the mounted discs. If only one disc is mounted, its root directory opens immediately, otherwise a menu is displayed.
• Adjust opens the New disc window.
• Shift-Select opens a menu of all mounted discs and dismounts one of them according to which entry you choose.
• Shift-Adjust opens the Choices window.
• Ctrl-Select and Ctrl-Adjust issue raFS_Unsafe and raFS_Safe respectively, which switch write through buffering on and off.
• Shift-Ctrl-Select causes a flush.
• Shift-Ctrl-Adjust executes raFS_Safe -smash to switch write through buffering off immediately.

Directory cache: This part of the window controls raFS' directory cache, which is used by the filing system to speed up accesses to its discs. When you make changes to a directory, e.g. by deleting a file, the changed directory information is not saved to the host filing system immediately, but only after a certain delay or after a given number of modifications, whichever of the two happens first.

Note: The fact that directories are usually only saved after a delay means that if you change the directory contents and then reset your computer immediately afterwards (or it crashes), the directory information as stored on the host filing system will not yet have been brought up to date. If you open the directory again later, deleted files will still appear to exist and new files won't appear in the directory display! This must be prevented from happening, so if you run software that crashes a lot, especially while accessing the filing system, you should disable the delay as follows:

For both the field where the delay in centiseconds is entered and the field containing the number of modifications, the values 0 and 1 have a special meaning: 0 tells raFS to completely disable saving of directories automatically after a delay or after any number of modifications, respectively. (If both values are 0, changed directories are only saved to make room if the maximum directory cache size has been reached, and when discs are dismounted.) A value of 1 in either of the two fields forces immediate write-through of any changes to the host filing system. (If you know a little about *commands, you can deal more elegantly with frequently crashing applications by adding raFS_Unsafe and raFS_Safe commands to their !Run files.)

Miscellaneous: A number of options for raFSFiler.

• Look for "!Mount": If switched on, raFSFiler looks for files called !Mount in any directories that open, and executes them.
• Adjust-close of "raFS:$" opens parent: If switched on, closing the root directory of a raFS disc with Adjust opens the parent of that disc's storage directory.
• Menu entry Quit in icon bar menu: If you dislike that raFSFiler, unlike ADFSFiler, has a Quit entry in its icon bar, you can switch off this option.
• Quit RMKills: Controls whether the two raFS modules are removed from memory when you select the Quit menu entry. Note that doing this for the raFS module means that all discs will be dismounted.

At the bottom of the window there are four buttons: Default fills in the "factory default" values for all the fields bar the first three. Save causes the values to be used and also stores them on disc. The Cancel button prevents any changes made to the fields from coming into effect - you can also click on it with Adjust to have the current values filled in once more. Finally, Set makes raFS use the supplied values, but only for the current session. If you click on the last three buttons with Select, the Choices window is closed; if you use Adjust, it remains open.

Back to the top of the page

Verifying corrupted discs

Do not attempt to delete those files of a corrupted disc that give errors - by doing this, you might delete the data of other files!

The verify operation offers a means to detect and repair corrupted discs. To start verifying, select the disc name from the Verify submenu of the icon bar menu (or use the Verify command). Instead of clicking on the disc name you can also just select the Verify entry, which automatically picks those discs for verifying that caused errors earlier on. The names of the directories being scanned will be printed, along with other messages, some of which need further explaining:

• Correcting: First unfilled directory is 'A0.B0': This can even happen for correct discs and is nothing to worry about.
• Different file lengths! 'Fix' to assume data in 'A0.B0.C0' belongs to '$.File'. 'Skip' if data belongs to a different file: You are given a choice here, as raFS is not sure whether the directory entry points to the correct data (and there may be another directory entry which is correct!). If you are unsure what to answer, choose Skip.
• Will set the file length to zero / will turn the directory into an empty directory: This does not mean that the file or directory will be deleted - instead, the data has already been lost and raFS just removes the reference to it.
• Sorry, the names of the remaining X files are lost! Will insert the files in 'Lost+Found': The number of files actually inserted could be less than what the message says, as unreferenced files with a file length of zero are not inserted, instead they are deleted.

Back to the top of the page

Contacting the author

My email address is atterer@augsburg.baynet.de (PGP key). To get the latest version of raFS, have a look at my homepage at http://home.augsburg.baynet.de/richard.atterer/.

In case you want to pay me a visit and beat me up because raFS corrupted all your data, this is the snail mail address:

        Richard Atterer
        Beethovenstraße 30
        86391 Stadtbergen
        Germany

Back to the top of the page

Version history

V1.15 (14-11-1998)

• Less stringent behaviour if Lock files remain in discs' directories after a crash or reset: Only a warning is given. If a Wimp error box opens, it closes automatically after a specified delay,
• Selecting the Verify entry of the icon bar menu or using Verify * now "does the right thing", verifying those discs that need verifying,
• Bugfix in the verify code: Open files are now taken into account,
• If !raFS is placed in !Boot.Choices.Boot.PreDesk, the mounting of the discs to be mounted on startup is no longer delayed until the Welcome screen has been displayed,
• New command raFSFiler_Menu creates user-definable menus of disc names; the default choices were changed to use it,
• The rafsln utility allows reading raFS discs on any Unix system - a binary for ARMLinux is supplied with the source code,
• Some improvements to make raFS work on write-protected DOS-formatted floppy discs - the discs must be mounted using the -ro switch,
• raFSFiler now looks for !Mount in the root of image files,
• Vincent Lefevre kindly translated the templates and messages into French,
• Corrected mistake in Mount which didn't make the command accept all combinations of the command line switches.

• Verify detects errors in discs and repairs them,
• A Lock file is saved to the storage directory when a disc is mounted, which allows for detection of read-only media and renamed storage directories,
• Opening directories for input (used by some programs to test their presence) now works regardless of the access details,
• Files opened for output only can also be read from,
• The RiscOS 3.1 version supports using the RMA instead of the sprite area to avoid clashes with other programs,
• The !Atterer, !Mount and !Dismount files can also be called _Atterer, _Mount and _Dismount for compatibility with ISO CD ROMs,
• raFSFiler now uses the ANT URL message as well as the URI protocol to launch URLs,
• Typing a very long name in the 'Create new disc' window no longer corrupts the contents of the disc name icon,
• Some minor bugs fixed.

• I was very tempted to finally add an easter egg to raFS, but refrained from doing it, as it's probably not the kind of feature people want to see in a filing system :-)
• Two bugs were fixed in an intermediate version 1.12a: One sometimes caused an undefined instruction exception in raFSFiler, the other prevented raFS_Opt from working in most cases, as the -LoadMessages switch had accidentally been made mandatory,
• raFSFiler was extended to allow for up to three discs to be mounted during start-up and to execute different commands for clicks on the icon bar with Shift or Ctrl pressed. Furthermore, new options enable you to switch off the Wimp filter on the Filer and to influence the behaviour of the Quit menu entry.
• In the New disc window, creating a disc with the same name for the disc name and storage directory is much easier. (Also added support for Ctrl-C to copy the name from the upper into the lower icon.)
• Adjust clicks on the close icon of an raFS disc cause the parent of the disc's storage directory to be opened. Apologies to James Larcombe, who implemented this in a separate module only to find I had already added it to raFSFiler myself!
• Added raFS_ExecAfter,
• Some basic checking of storage directory names - warns you if you attempt to mount an raFS disc which is stored on raFS,
• raFS_Opt -OpenRename controls whether open files can be renamed. By default, this is now possible,
• Added a -verbose switch to raFS_Unsafe and raFS_Safe
• The raFS$NoChecks variable has been extended to allow for image file types to be excluded from the stricter integrity checks,
• You can specify a default !Dismount file in the Messages to make raFS_Create automatically write into new storage directories. However, by default no !Dismount file is created,
• Fixed a memory leak in raFSFiler, when the module was quit and subsequently restarted with Desktop_raFSFiler,
• Name of the dynamic area is internationalised,
• Bugfix: If a file without write access was opened using OPENOUT, an error was returned correctly for attempts to write, but the file extent was reset to zero nevertheless. The behaviour is now exactly the same as for FileCore: The file extent is reported as zero, but in reality remains unaltered.

Released on an Acorn User cover disc.

• There's now a mechanism which avoids having to supply multiple copies of the raFS(Spr) modules for different countries; you can override the hard-coded English defaults in a Messages file given to raFS with raFS_Opt -LoadMessages
• Dutch translation of the program texts kindly donated by Dick Tanis - thanks!
• The extent of image files could still be set to zero - this is now definitely fixed. However, the new behaviour causes the creating of new SparkFS archives on top of old ones to fail,
• Directories can no longer be moved into themselves - this caused the directory's contents to become inaccessible,
• "Workaround" for the rename submenu title being truncated to "Enter new na" - changed the text to "New name" :-) The truncation is caused by a bug in MessageTrans 0.31 and earlier - it has been fixed in V0.32,
• Corrected mistakes in V1.11 which lead to Does not belong to this directory entry or Not open for update errors,
• No longer complains about Disc already mounted if the case of some characters in the storage directory path differs from what was used initially to mount the disc.

• Workaround for dangerous bug: The extent of image files was sometimes set to zero when the file was accessed,
• Major bug fixed: If a file was overwritten by saving on top of it, the directory data wasn't marked as changed, which could result in Does not belong to this directory entry errors,
• Fixed another bug which also caused Does not belong to this directory entry if a file was opened with OPENOUT and then not stamped after it had been closed,
• Sequential pointer is now set to the correct value for attempts of reading data off the end of the file,
• (Hopefully) fixed problem with raFSFiler submenu title being displayed as "Enter new na",
• Can now also use -newdisc switch with Desktop_raFSFiler to open the "Create new disc" dialogue box,
• In the "Create new disc" dialogue box, dragging the icon to a directory display immediately creates the disc,
• Added Free,
• Corrected behaviour of Mount - now doesn't set the CSD to the new disc's root, but only FileSwitch$raFS$CSD,
• If there is no CSD (e.g. after NoDir), Dir and Cat now access the disc's root instead of giving Disc not present,
• (RiscPC version only) Bug fixed: Errors while saving directory data could cause Directory data not valid errors later on,
• Maximum size of dynamic area is no longer the total RAM size, but only 1 MB,
• Fixed problem with raFSFiler complaining about Message file already open,
• Directory data is now stamped as Data (&FFD) on the host FS under all circumstances.

• There is now an raFSFiler!
• raFS has been registered with Acorn and has been assigned the filing system number 142,
• Major update of documentation, German translation of the first part,
• The FS module can be called directly from assembler,
• Finally added support for flushing directories after a delay (-DirsaveDelay switch of raFS_Opt) or after a given number of changes to the directory data (-DirsaveMods switch),
• Added raFS_Unsafe and raFS_Safe for temporarily forcing write-through for directory buffer,
• Support for !Mount and !Dismount files added, together with -X switch for the Mount command,
• Mount and Dismount set raFS$(D)Disc to the (dis)mounted disc's name,
• raFS_Create now writes a !Mount file to storage directories it sets up. The new -app switch causes it to also add !Sprites and !Run files for application directories,
• Added disc integrity checks to open, load, save, delete and create operations, and support for the raFS$NoChecks variable,
• Fixed a "feature" which meant that when you renamed a file to be in a different directory, raFS always attempted to load it into memory, but then threw it away again immediately - oops! :-)
• NameDisc didn't check at all whether a disc with the desired new name was already mounted - it now gives an error if this is the case. Additionally, the changed !Atterer file is now saved immediately after the command, and the new disc name can be longer than 10 characters (didn't work because OS_FSControl 50 was used - now alters the name directly),
• Mount no longer fails to notice that a disc of the same name is already mounted if the case of one or more characters of the names differs,
• Fixed a quite serious bug occurring during a Close on one of raFS' host filing systems, when raFS had files open on that filing system,
• When Service_Shutdown is received, now doesn't dismount all discs any longer (which prevented Wimp applications that closed down after it from saving anything to raFS discs), but instead does the equivalent of an raFS_Unsafe (only if raFS_Unsafe hasn't already been issued),
• Minor bug fixed: Under unlikely circumstances, an error during saving a file could result an unreferenced file to be left behind,
• When the module is RMRun, raFS is selected as the current filing system,
• Maximum number of discs increased to 50, default directory buffer size is now 30k.

• Added raFS_Discs,
• When a file is opened for output only, not for update, its extent is now set to zero. Because the calls made to raFS are exactly the same in those two cases, this is achieved by the routine on FindV taking note of what the last reason code passed to OS_Find was,
• Changed Mount, Dismount and NameDisc into filing system commands,
• Added the -path switch to Mount,
• Mount no longer gives an error when trying to mount the same disc twice; it and Dismount (un)set the CSD/URD correctly,
• Fixed a bug which prevented you from re-opening directories once they had been flushed to disc, if any of the directory entries' names contained one of the characters #%&*@\^
• Back works now,
• File formats are explained in this document.

• Fixed a bug in raFS_Flush and Dismount,
• Separate RiscPC-only version of module using a dynamic area.

• First release: Long filenames, any number of objects per dir, directory cacheing; no file cacheing or auto-flushing of directory cache.

Back to the top of the page

Copyright

No profit must be made when the program is spread - any charges must not exceed the cost of spreading (e.g. discs, postage). You must always pass on all files of the program, including this copyright notice.

You may distribute this program together with any other product, commercial or non-commercial, that depends on or is enhanced by this program, without informing the author in advance. If you re-distribute the program in this way, you are obliged to send one copy of your product, and of any further versions as long as they still include this program, to the above address free of charge. (When sending to the email address, please ask before sending large archives.)

Because this program is distributed free of charge, there is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing, the author provides the program "as is", without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing will the author be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if the author has been advised of the possibility of such damages.

Back to the top of the page